home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
The 640 MEG Shareware Studio 2
/
The 640 Meg Shareware Studio CD-ROM Volume II (Data Express)(1993).ISO
/
pascal
/
boost4.zip
/
MANUAL.400
< prev
next >
Wrap
Text File
|
1988-03-28
|
54KB
|
1,308 lines
BOOSTERS 4.0
Tools for Turbo Pascal Programmers
Users Guide
Part I
Copyright (C) 1988 George F. Smith & Company
All Rights Reserved
The Boosters library of routines and its documentation are
protected by the Copyright Laws of the United States. They
may not be resold, distributed, or copied without permission
in writing from George F. Smith and Company. The only
exception is the right of the purchaser of Boosters to make an
archival copy of the distribution diskettes as a means of
securing his or her investment.
For information about Boosters, please contact:
George F. Smith & Company
609 Candlewick Lane
Lilburn, GA 30247
(404) 923-6879
Trademarks
----------
Turbo Pascal is a trademark of Borland International, Inc.,
Scotts Valley, CA.
IBM PC, PS/2 are products of International Business Machines,
Inc., Boca Raton, FL.
Acknowledgements
----------------
I wish to thank Bill Meyer of Doraville, Georgia and John
Jones of LaGrange Park, Illinois for their invaluable aid in
getting Boosters ready for Turbo Pascal 4.0. They served as
testers, advisers, and in John's case, a producer of the
labels for the distribution diskettes.
Boosters in General
-------------------
Boosters was conceived and created to make professional or
often-used programming techniques readily available whenever I
needed them. It occurred to me that other programmers may
find them useful, so through various channels they have made
it to PCs all across North America and to more exotic places I
someday hope to visit, such as Finland and Australia.
Boosters supports string, video, heap, dos, and special-effects
routines in TEXT mode, for any IBM PC/PS or true compatible.
Many Boosters routines are coded in assembly language for speed
and compactness.
Nowadays, of course, windowed video interfaces are standard
components of most programs, even Q&Ds. As an aid in getting
(text) screens defined quickly and easily, Boosters also
includes ScrGen, a screen generator. It comes with three
online help panels and has been converted and upgraded for the
current release. ScrGen lets you create and edit screens,
while Boosters provides routines that allow programs to access
the screens and use them in your programs.
Boosters Version 4.0
--------------------
Boosters has been available as a support library for Turbo
Pascal since November, 1985. None of the earlier releases
will work correctly with Turbo Pascal 4.0 (or higher), due
to fundamental changes in the operation of the compiler.
The most recent release of Boosters prior to 4.0 was 2.01,
which like its predecessors was a combination of inline
and Pascal routines. To use a given routine from one of the
older versions, it was necessary to $Include it from a disk
file or copy it into the editor file.
With version 4.0, programmers have in effect an extension of
the Pascal language. By simply coding a "Uses Boosters;"
statement at the beginning of a program, they have access to
90 functions and procedures as defined and linked by the
Boosters Unit (Boosters.TPU).
A simple 'Hello, world' program under version 4.0 might look
like:
Program World;
Uses Boosters;
begin
PutStr (h,'Hello, World',1,1,14);
end.
Fortunately, most of the changes to the Boosters library in
version 4.0 are internal to the routines. They do not affect
the manner in which they are used in a Turbo Pascal program.
There are some important distinctions and assumptions,
however, that we will now discuss in detail.
BOOSTERS UNIT
-------------
As mentioned, the Boosters library is now a Turbo Pascal Unit,
which means that the Boosters.TPU file must be accessible to
your programs. You have been provided both the TPU and the
PAS version of the unit on the distribution diskettes.
h, v, and heap
--------------
Within the interface section of the Boosters unit are type,
constant, and variable definitions that in previous versions
were located in file BoDecl.Pas. Version 4.0 retains the
constants 'h' and 'v' for use with PutStr and GetStr, as well
as names relating to heap operations, such as HeapBuf and
HeapTop.
However, the interface section has dropped
Page : array[1..2] of HeapBuf;
and replaced it with
Hpage : HeapBuf;
In your programs, therefore, you will have to define the heap
pages you are accessing. As a suggestion, you could use:
Const
Npage = 5;
Var
Page : array[1..Npage] of HeapBuf;
i : Integer;
.
.
.
BEGIN
Mark (HeapTop);
for i := 1 to Npage do New(Page[i]);
.
.
.
Release (HeapTop);
END. { Main Program }
Please notice that the variable 'i' will now be defined in
your programs, as well. It is not necessary to manage the
heap with Mark and Release, but it is necessary to manage the
heap, so take care. Turbo Pascal v4.0 has a new compiler
directive, $M, that allows you to establish stack, minimum
heap, and maximum heap sizes. See page 534 of the Turbo
Pascal v4.0 manual for a definition of $M. (If you use Turbo
Pascal's Exec procedure, you must override the $M heapmax
default to make room for the child process.)
ColumnType and RowType
----------------------
Also, Boosters no longer has the ColumnType and RowType
definitions. The heap and video routines that used these
defintions have been redefined to accept integers as
replacements.
Dos Registers and Ch
--------------------
Turbo Pascal comes with units of its own, most notably Crt and
Dos. Both of these units are used by the Boosters unit.
Within the Dos unit is a definition of the 8088's registers,
called, appropriately, 'registers' (see page 299). As you will
notice, Boosters.Pas uses the Dos unit's definition of this
Type and calls it 'regs'--just as in previous Boosters
versions.
Since the Dos registers Type includes definitions for the 8-
bit registers, one of which is named Ch, I decided to drop the
definition of the Char type, Ch, from the Boosters unit.
AnyString
---------
Boosters' Type AnyString = string[255] is no longer needed
since Turbo Pascal now has a Type String with the same
definition. The generic string variable 's' is no longer part
of Boosters. The demonstration programs use
var s : string;
as a general string variable.
SnowRemoval and VideoSeg
------------------------
Earlier versions of Boosters had code embedded in each video
routine that attempted to isolate the CGA from other video
adapters so the programs could perform their functions at
maximum speed without creating snow on the screen.
There were several problems with this approach. One, the
Boosters routines could not distinguish between a CGA and an
EGA, for instance, and ended up executing snow removal code
when it wasn't necessary. Two, executing snow removal
routines slows video operations. So for an EGA, for instance,
programmers (and users of their programs) had to pay a speed
penalty. Three, Boosters gave programmers no choice about
whether to remove snow or not. There are users who would
gladly tolerate some snow for an increase in performance,
especially since the snow effect can be neutralized somewhat
through the use of colored screen backgrounds.
Boosters v4.0 largely corrects this situation. It uses a
boolean variable, SnowRemoval, to determine whether to execute
snow removal code or not. SnowRemoval is initialized to FALSE
in the initialization section of the Boosters unit. Your
programs can manipulate this variable based on user input or
adapter board detection code. A commercial product called
Turbo Express, available at many software outlets, comes with
adapter board detection algorithms, I'm told. Anyway, with
SnowRemoval set to FALSE, the video routines will NOT perform
snow removal, which for virtually all boards is unnecessary.
Each assembler video routine used to inspect location 449h to
determine whether the adapter board installed was monochrome
(7) or graphics (not 7). Monochrome adapters start video
memory at segment B000h, while grpahics adapters start at
B800h. For version 4.0, this logic has been moved out of the
assembler routines and into the initialization section of the
Boosters unit. This again places control of the video segment
address into the programmer's hands, while in theory picking
up some speed during execution.
Boosters tests LastMode, a Turbo Pascal variable, to determine
whether to assign VideoSeg a value of B000h or B800h.
The New and the Missing
-----------------------
New routines for Boosters include the following:
Dow
Fil2Heap
GchaHeap
GetHeap
GetSize
Input2
PchaHeap
SplitCloseH
SplitCloseV
SplitOpenH
SplitOpenV
Translate
Verify
WordInd
In addition, several others have been modified either in name
or function:
ChooseOption .. Returns last key pressed
Fstr .......... Argument type changed from Integer to
LongInt
FstrHeap ...... Now allows users to set starting x,y
values for search)
HeapAtt ....... Formerly HeapAt
Hwipe ......... First argument is Page:HeapBuf rather than
Page:Integer
Input ......... Fixes a problem with moving left over blank
filters
ShowDate ...... Added a parameter to specify attribute
ShowTime ...... Added a parameter to specify attribute
Vwipe ......... First argument is Page:HeapBuf rather than
Page:Integer
Wait .......... Returns key pressed during pause
WordN ......... Formerly Word
Missing from the lineup is the Exec procedure, a version of
which is now included with the Dos unit. Memory size
requirements are coded with the $M directive, rather than as
an argument to the procedure.
Using Boosters with the heap
----------------------------
Under Boosters, the heap serves as offstage video memory. The
heap routines always assume they are working with a character-
attribute layout. Using the heap in this manner allows you to
retain and manipulate complex or otherwise important video
data without first converting it. And since data on the heap
is display-ready, it can be copied to video memory
instantaneously.
With your data residing on the heap, there is no limit to the
amount of memory available, other than physical- or operating
system-imposed restrictions.
As an example of using the heap with Boosters, let's assume
you have an application that requires one main menu and a help
screen. First, create the screens with ScrGen, saving them to
a file named Sample.Gen. Save the main menu as screen 1, the
help panel as screen 2. While you're in ScrGen and working
with the main menu, use the ruler (Alt-U) to note the
coordinates of the menu's selections.
Your program to control the screens and the users' responses
might look something like the following:
Program Sample;
Uses Crt,Boosters;
Const
npage = 2; { number of heap pages to allocate }
F1 = #59; { F1 invokes the help screen }
AltX = #45; { Alt-X ends the program }
var
i,
ecode : Integer
Page : array[1..npage] of HeapBuf; { HeapBuf is defined
in Boosters.Pas }
UserQuits : Boolean;
c : char;
BEGIN
{--- Initialize variables ---}
UserQuits := false;
{--- Mark and allocate heap storage ---}
Mark ( HeapTop );
for i := 1 to npage do new ( page[i] );
{--- Read ScrGen files into heap memory ---}
{ the main menu will be on page 1, }
{ the help panel on page 2 }
Fil2Heap ( 'Sample.Gen', 1, npage, Page[1], Ecode );
{--- If an error occurred, display message and halt ---}
if ecode > 0 then begin
putstr ( h,'Error reading Sample.Gen',1,1,14);
exit;
end;
{--- Display the main menu from page 1 of the heap ---}
RestoreScreen ( Page[1] );
{--- Process the user's key strokes ---}
repeat
c := readkey;
if c = #0 then begin
c := readkey;
case c of
F1 : begin
{--- display help screen ---}
RestoreScreen ( Page[2] );
{--- Wait for user's keypress ---}
c := readkey;
if c := #0 then c := readkey;
{--- Restore main menu ---}
RestoreScreen ( Page[1] );
end;
{--- Set flag when user presses Alt-X ---}
AltX : UserQuits := true;
.
. {--- Process other keys ---}
.
end; { case }
.
. {--- Execute the user's menu choices ---}
.
until UserQuits;
Release ( HeapTop );
END. { Sample program }
For additional examples of using Boosters in Turbo Pascal
programs, you are strongly urged to review the demonstration
programs provided with the distribution diskettes.
Reference Guide
---------------
This section describes the routines of Boosters version 4.0.
The routines are presented alphabetically.
The declarations that follow assume these definitions,
which are included in Boosters.Pas:
Type
HeapBuf = ^AnyBuf;
AnyBuf = Record
Screen : Array[1..4000] of Byte;
End;
Var
HPage : HeapBuf;
The heap examples assume Page to be defined as an array of
HeapBuf:
Const
Npage = 2; { Number of heap pages }
Var
Page : array[1..Npage] of HeapBuf;
-----------------------------------------------------------
BoDir Procedure
-----------------------------------------------------------
Purpose Displays a windowed directory
Declaration BoDir ( var FileSpec,FileName : String;
x1,y1,x2,y2 : Integer;
style, attr : byte );
Remarks Displays the directory specified in FileSpec
within a box defined by (x1,y1), (x2,y2).
Style and attr define the box's line-type
and video attribute.
The box size must have as a minimum x2 >
(x1+16) and y2 > (y1+3).
The directory is windowed within the box.
Files are identified by color:
User files - intense yellow
Subdirectories - intense red
Volume labels - green-blue bkgrnd
Hidden files - intense yellow/blue
When a box is full or the directory is
exhausted, BoDir pauses and waits for one
of these keypresses:
Cursor key - point to next file name
in current row/column.
Enter - Select file and assign it
to FileName
Escape - Abort directory display and
set FileName to null.
PgDn - Display more directory entries
or abort the display if none
are found. FileName is set to
null.
Example Display the default directory.
CurPath := '';
FileSpec := '';
BoDir ( FileSpec,FileName,20,5,60,12,1,14);
-----------------------------------------------------------
BoErase Procedure
-----------------------------------------------------------
Purpose Erases the specified file from disk.
Declaration BoErase ( FileName : String;
var Ecode : Integer );
Remarks Wild cards are not allowed.
Ecode values:
0 - successful
2 - file not found
5 - access denied
Example Erase Temp.Doc from the current directory.
BoErase ('Temp.Doc',Ecode);
if Ecode = 0 then
PutStr (h,'File erased',1,1,14);
-----------------------------------------------------------
BoRename Procedure
-----------------------------------------------------------
Purpose Renames a file on the current directory.
Declaration BoRename ( OldName, NewName : String;
var Ecode : Integer);
Remarks Take care to ensure that NewName does not
already exist.
Ecode values:
0 - successful
2 - OldName not found
3 - Path not found
5 - access denied
Example Rename Temp.Doc to Save.Doc.
BoRename ( 'Temp.Doc','Save.Doc',Ecode);
if ecode = 0 then
pdq ('e','File successfully renamed',1,1,14);
-----------------------------------------------------------
Box Procedure
-----------------------------------------------------------
Purpose Draws a box on the screen.
Declaration Box ( x1,y1,x2,y2,style,att : Integer);
Remarks Draws a box at (x1,y1) and (x2,y2), which
specifiy the upper-right and lower-left
coordinates, respectively.
Box does not clear the box interior. Use
Remblk or RemBlkr to clear the area inside
the box.
If Style > 4, then the sides of the box are
drawn with chr(style). If Style is in [1..4],
then Box draws a rectangle using the special
box-drawing characters:
Style Sides
1 single line
2 double line
3 top & bottom single,
others double
4 top & bottom double,
others single
Att sets the video attribute of the box sides.
See also BoxHeap
Example Draw an 80x25 box.
ClrScr;
Box ( 1,1,80,25,1,14);
-----------------------------------------------------------
BoxHeap Procedure
-----------------------------------------------------------
Purpose Draws a box on a page of the heap.
Declaration BoxHeap ( Page : Heapbuf;
x1,y1,x2,y2,style,att : Integer);
Remarks Draws a box at (x1,y1) and (x2,y2), which
specifiy the upper-right and lower-left
coordinates, respectively.
BoxHeap does not clear the box interior. Use
FillHeap to clear the area inside the box.
If Style > 4, then the sides of the box are
drawn with chr(style). If Style is in [1..4],
then Box draws a rectangle using the special
box-drawing characters:
Style Sides
1 single line
2 double line
3 top & bottom single,
others double
4 top & bottom double,
others single
Att sets the video attribute of the box sides.
See also Box
Example Draw a box on the heap and display it.
ClrScr;
SaveScreen ( Page[1] );
BoxHeap ( Page[1],10,5,70,15,1,14);
Heap2Scr ( Page[1],10,5,70,15,10,5);
-----------------------------------------------------------
Calendar Procedure
-----------------------------------------------------------
Purpose Draws a calendar on the screen for the
specified month and year.
Declaration Calendar ( mm,year,StartCol,StartRow:Integer);
Remarks The year must be 4 digits - 1966, not 66.
The upper-left screen coordinates of the
calendar are given by (StartCol,StartRow).
The calendar is 29 columns wide and 16 rows
long.
See also CalHeap
Example Display the calendar for December, 1982.
Calendar ( 12, 1982, 25, 6 );
-----------------------------------------------------------
CalHeap Procedure
-----------------------------------------------------------
Purpose Draws a calendar on a page of heap for the
specified month and year.
Declaration CalHeap ( Page : HeapBuf;
mm,year,StartCol,StartRow:Integer);
Remarks The year must be 4 digits - 1966, not 66.
The upper-left screen coordinates of the
calendar are given by (StartCol,StartRow).
The calendar is 29 columns wide and 16 rows
long.
See also Calendar
Example Display the calendar for August, 1981.
CalHeap ( Page[1], 8, 1981, 25, 6 );
Heap2Scr ( Page[1], 25,6,53,21,1,1);
-----------------------------------------------------------
CblkHeap Procedure
-----------------------------------------------------------
Purpose Copies a block on a page of heap.
Declaration CblkHeap ( Page : HeapBuf; x1,y1,x2,y2,
x3,y3 : Integer);
Remarks Copies the block on Page given by (x1,y1)
and (x2,y2) to (x3,y3).
See also MblkHeap
Example Build and copy a box on a page of heap.
BoxHeap ( Page, 25,10,40,20,1,14);
CblkHeap ( Page, 25,10,40,20,9,10);
-----------------------------------------------------------
Center Function
-----------------------------------------------------------
Purpose Returns a string centered within a field
of specified width.
Declaration Center ( s : string; Width:Integer; Pad : Char);
Result Type String
Remarks S is centered in the result string, padded on
the ends with Pad character. If S is longer
than Width, only the first Width characters of
S are returned.
See also CtrScr
Example Center 'Boosters v4.0' on line 1 of the screen.
PutStr (h,Center('Boosters v4.0',80,' '),
1,1,30);
-----------------------------------------------------------
ChgAtt Procedure
-----------------------------------------------------------
Purpose Changes the attribute of a block in video
memory.
Declaration ChgAtt (x1,y1,x2,y2 : Integer;
FromAtt, ToAtt : byte);
Remarks Changes all FromAtt attributes to ToAtt
attributes for the block defined by (x1,y1)
and (x2,y2).
See also SetAtt, HeapAtt
Example Change red background attributes to blue.
ChgAtt ( 1,1,40,15,$40,$10 );
Note that only screen positions having a red
background attribute ($40) will be changed to
blue ($10). All other positions will remain
the same.
-----------------------------------------------------------
ChooseOption Procedure
-----------------------------------------------------------
Purpose Allows the user to scroll a list of choices
within a menu.
Declaration ChooseOption ( x1,y1,x2,y2,Nentries ; Integer;
var lastkey : char );
Remarks Given a list of choices displayed within a
box, ChooseOption allows the user to wrap
through the choices with the up and down
arrow keys. LastKey indicates whether the
user canceled with Escape or selected with
Enter.
(x1,y1) are the coordinates of the upper-left
corner of the first selection (not the box),
while (x2,y2) are the lower-right coordinates
of the menu box. Nentries is the number of
entries in the menu.
Example Allow the user to choose from a menu of 3 items.
Box (20,6,60,16,1,14);
RemBlk ( 21,7,59,15);
CtrScr ( 'e',"Menu',39,21,7,30);
pdq ('e','Breakfast',22,10,14);
pdq ('e','Lunch',22,11,14);
pdq ('e','Dinner',22,12,14);
ChooseOption ( 22,10,60,16,3,LastKey);
if LastKey = #13 then begin
GetStr ( h,s,22,WhereY,10);
PutStr ( h,'Meal selected is '+
strip(s,' '),1,1,14);
end;
-----------------------------------------------------------
CntCh Function
-----------------------------------------------------------
Purpose Returns the number of occurrences of a
character in a string.
Declaration CntCh ( S : String; C : Char ) : Integer;
Result Type Integer
Remarks The search is case sensitive--'E' and 'e'
are regarded as different characters.
Example Count all occurrences of all letter E's,
both upper- and lower-case.
S := 'Easy does it';
n := CntCh ( Upper(S),'E');
-----------------------------------------------------------
Copies Function
-----------------------------------------------------------
Purpose Returns N concatenated copies of character C.
Declaration Copies ( C : Char; N : Integer ) : String;
Result Type String
See also CopyStr
Example Create a string of 30 underscores.
s := copies('_',30);
-----------------------------------------------------------
CopyBlk Procedure
-----------------------------------------------------------
Purpose Duplicates a block in video memory.
Declaration CopyBlk ( x1,y1,x2,y2,x3,y3 );
Remarks Copies the block at (x1,y1) and (x2,y2) to the
location beginning at (x3,y3).
See also MoveBlk,CblkHeap
Example Create a box and copy it to another area of the
screen.
Box ( 20,5,40,15,1,14 );
CopyBlk ( 20,5,40,15,50,5 );
-----------------------------------------------------------
CopyStr Function
-----------------------------------------------------------
Purpose Returns N concatenated copies of string S.
Declaration CopyStr ( S : String; N : Integer ) : String;
Result Type String
See also Copies
Example Create 5 copies of 'beep-'.
s := copies('beep-',5);
-----------------------------------------------------------
CtrScr Procedure
-----------------------------------------------------------
Purpose Center a string in video memory.
Declaration CtrScr (nsew : char; s : string;
length, x, y : Integer; att : byte);
Remarks Centers S on the screen within a field of
length 'length', which begins at (x,y). Att
specifies the attribute of the centered string.
NSEW determines the direction of output:
N - North, bottom to top
S - South, top to bottom
E - East, left to right (normal)
W - West, right to left
CtrScr does not alter the cursor position.
See also Pdq, PutStr
Example Center a string at the top pf the screen.
CtrScr ('e','Page 1',80,1,1,30);
-----------------------------------------------------------
CursorOff Procedure
-----------------------------------------------------------
Purpose Makes the cursor invisible.
Declaration CursorOff;
Remarks Calls Bios interrupt 10h to turn off the
cursor.
See also CursorOn, SetCursor
Example Remove the cursor from the screen.
CursorOff;
-----------------------------------------------------------
CursorOn Procedure
-----------------------------------------------------------
Purpose Defines a cursor of standard size.
Declaration CursorOn;
Remarks Calls Bios interrupt 10h to set the cursor.
Uses Boosters' VideoStatus variable to
determine whether monochrome or color screen.
See also CursorOff, SetCursor
Example Turn on the cursor.
CursorOn;
-----------------------------------------------------------
DiffOne Procedure
-----------------------------------------------------------
Purpose Advances cursor to the first screen position
different from the current one.
Declaration DiffOne ( EW : Char );
Remarks Places cursor at first position that does
not match the character/attribute of current
cursor position. If EW is 'E' or 'e', the
search is east (left-to-right). If EW is 'W'
or 'w', the search is west (right-to-left).
If DiffOne cannot find a non-matching position,
it places the cursor at (80,25) for east
searches or (1,1) for west searches.
Example Advance the cursor to the next differing
position.
DiffOne ( 'e' );
-----------------------------------------------------------
Disk2Mem Procedure
-----------------------------------------------------------
Purpose Copies a screen image from a disk file to a
page of heap.
Declaration Disk2Mem ( FileDesc : String;
ScreenNumber : Integer;
Page : HeapBuf;
var Ecode : Integer );
Remarks FileDesc specifies the Drive/Path/FileName,
while ScreenNumber indicates the screen
number within the file to read.
Screens are 4000 bytes each and are assumed to
be images of video memory (character/attribute
pairs). A common use of this procedure is to
read files created with Boosters' ScrGen.
Ecode indicates the status of the operation:
0 - Screen found and loaded onto heap
3 - Path or file not found
4 - no file handle available
5 - access denied
See also Fil2Heap
Example Read screen 4 of a file into page 1 of heap memory,
then display it.
Disk2Mem ( 'Layout.Gen',4,page[1], Ecode );
if Ecode = 0 then
RestoreScreen ( Page[1] );
-----------------------------------------------------------
Dows Function
-----------------------------------------------------------
Purpose Returns a day of the week string.
Declaration Dows ( Month, Day, Year : Integer ) : String;
Result Type String
Remarks The year must be 4 digits: for example, 1955.
The strings returned are: Sunday, Monday,
Tuesday, Wednesday, Thursday, Friday,
Saturday. They are are returned exactly as
shown, first letter capitalized.
See also Dow
Example Find the day of the week for December 14, 1982.
s := dows( 12, 14, 1982 );
pdq ('e','December 14, 1982 was a '+
s,1,1,14);
-----------------------------------------------------------
Dow Function
-----------------------------------------------------------
Purpose Returns a day of the week index.
Declaration Dows ( Month, Day, Year : Integer ) : Integer;
Result Type Integer
Remarks The year must be 4 digits: for example, 1955.
The values returned and their meaning are:
0 - Sunday
1 - Monday
2 - Tuesday
3 - Wednesday
4 - Thursday
5 - Friday
6 - Saturday
See also Dows
Example Find the day of the week for December 14, 1982.
if 'Days' is defined as:
const
days : array[0..6] of string[2] =
('Su','Mo','Tu','We','Th','Fr','Sa');
then the function call for 12/14/1982 will be:
n := dow( 12, 14, 1982 );
pdq ('e','December 14, 1982 was a '+
days[n],1,1,14);
-----------------------------------------------------------------
DriveCnt Function
-----------------------------------------------------------
Purpose Returns the number of logical disk drives on
the host CPU.
Declaration DriveCnt : Integer;
Result Type Integer
Remarks This function issues a call to DOS function
0Eh, which returns an initial drive count,
then follows with repeated calls to DOS
function 47h until the count is verified as
correct.
Example Display the number of drives on the system.
Write('Number of drives is ',DriveCnt);
-----------------------------------------------------------
Fil2Heap Procedure
-----------------------------------------------------------
Purpose Copies a range of screen images into a range
of heap pages.
Declaration Fil2Heap ( FileDesc : String;
FromScreen, ToScreen : Integer;
Page : HeapBuf;
var Ecode : Integer );
Remarks FileDesc specifies the Drive/Path/FileName,
while FromScreen, ToScreen indicate the
starting and ending screens to read into
the heap beginning at Page.
Screens are 4000 bytes each and are assumed to
be images of video memory (character/attribute
pairs). A common use of this procedure is to
read files created with Boosters' ScrGen.
Ecode indicates the status of the operation:
0 - Screen found and loaded onto heap
3 - Path or file not found
4 - no file handle available
5 - access denied
See also Disk2Mem
Example Read screens 4 through 7 into the heap beginning
at Page[1].
Fil2Heap ( 'Layout.Gen',4,7,page[1], Ecode );
if Ecode = 0 then
RestoreScreen ( Page[1] );
-----------------------------------------------------------
FileStamp Procedure
-----------------------------------------------------------
Purpose Gets or sets a file's time/date stamp.
Declaration FileStamp ( FileName : String;
GetSet : Integer;
Var Ecode : Integer );
Remarks Attempts to open FileName, read or write
the time/date stamp, and close the file.
GetSet = 0 for reading, GetSet = 1 for
writing time/date.
Uses global variables:
FileHH, FileMin, FileSec (time)
FileYY, FileMM, FileDD (date)
FileYY must be 4 digits - e.g., 1988.
FileHH (hour) is in military format -
e.g., 2:00 p.m. is 14.
Ecode = 0 if the operation was successful,
or a DOS error code if unsuccessful.
See also GetFtime (in Turbo Pascal DOS unit)
Example Read the file stamp for Boosters.Pas.
FileStamp ( 'Boosters.Pas',0,Ecode );
if Ecode = 0 then begin
WriteLn(FileHH,':',FileMin,':',FileSec);
WriteLn(FileMM,'/',FileDD, '/',FileYY-1900);
end;
-----------------------------------------------------------
FillHeap Procedure
-----------------------------------------------------------
Purpose Initializes a block of heap.
Declaration FillHeap ( Page : HeapBuf;
x1,y1,x2,y2 : Integer;
C : Char; Att : Byte );
Remarks The block defined by (x1,y1) and (x2,y2) is
set to values specified by C and Att.
Example Clear a page of heap without disturbing the
screen.
FillHeap ( 1,1,80,25,#32,7 );
-----------------------------------------------------------
FindStr Procedure
-----------------------------------------------------------
Purpose Searches video memory for string S,
positioning the cursor at a specified point
relative to S.
Declaration FindStr ( x,y : Integer; s : string;
offset : Integer;
var ecode : Integer );
Remarks Beginning at (x,y), FindStr searches for S.
If S is found, FindStr sets Ecode = 0 and
places the cursor according to the value of
OffSet:
OffSet Cursor Placement
=0 S[1]
<0 S[1]-OffSet
>0 S[1]+OffSet
If FindStr can't find S, it sets Ecode = 1 and
puts the cursor at (80,25).
See also FstrHeap
Example Search for 'log' and highlight the 'g' if
found.
FindStr ( 1,1,'log',2,ecode);
if ecode = 0 then
SetAtt (Wherex,WhereY,WhereX,WhereY,112);
-----------------------------------------------------------
Fstr Function
-----------------------------------------------------------
Purpose Converts a LongInt to a string.
Declaration Fstr (num:LongInt; width:Integer) : String;
Result Type String
Remarks Num is converted to a string, right-justified
in a field of Width characters. This is
Turbo's Str procedure made available as a
function for convenience.
Example Display Integer 15 using Pdq.
n := 15;
Pdq('e',Fstr(n,3),15,5,14);
-----------------------------------------------------------
FstrHeap Procedure
-----------------------------------------------------------
Purpose Searches a page of heap for string S.
Declaration FstrHeap ( Hpage:HeapBuf; S:String;
var x,y,ecode : Integer);
Remarks Beginning at (x,y) on Page, FstrHeap searches
for S. If S is found, FstrHeap sets Ecode = 0
and returns the coordinates of S[1] in (x,y).
FstrHeap sets Ecode = 1 if it cannot find
S on Page.
See also FindStr
Example Find 'log' on page 1 of the heap and load
it into S.
x := 1;
y := 1;
FstrHeap ( Page[1],'log',x,y,ecode );
if ecode = 0 then
GetHeap ( Page[1],h,s,x,y,3);
-----------------------------------------------------------
GchaHeap Function
-----------------------------------------------------------
Purpose Gets a character/attribute word from the heap.
Declaration GchaHeap ( Hpage:HeapBuf; x,y:Integer ) :Integer;
Result Type Integer
Remarks Returns the character/attribute pair located
at (x,y) on Page.
See also PchaHeap
Example Get the character/attribute combination at 1,1
on page 2 of the heap.
n := GchaHeap ( Page[2],1,1);
-----------------------------------------------------------
GetAtt Function
-----------------------------------------------------------
Purpose Gets the video attribute at (x,y).
Declaration GetAtt ( x,y:Integer ) : byte;
Result Type Byte
Remarks Returns the attribute found at (x,y) of
video memory.
See also GetChar, HeapAtt.
Example Get the attribute associated with the first
character of the string, 'Menu', in video
memory.
FindStr ( 1,1,'Menu',0,ecode);
if ecode = 0 then
n := GetAtt ( WhereX,WhereY );
-----------------------------------------------------------
GetChar Function
-----------------------------------------------------------
Purpose Gets the character at (x,y) on the screen.
Declaration GetChar ( x,y:Integer ) : Char;
Result Type Char
Remarks Returns the character found at (x,y) of
video memory.
See also GetAtt.
Example Get the character following the colon on
line 3 of the screen.
FindStr ( 1,3,':',1,ecode);
if ecode = 0 then
c := GetChar ( WhereX,WhereY );
-----------------------------------------------------------
GetHeap Procedure
-----------------------------------------------------------
Purpose Reads a string from a page of heap.
Declaration GetHeap ( Hpage:HeapBuf; hv:Char; S:String;
x,y,len : Integer );
Remarks Reads Len characters into S beginning at
(x,y) of Page. If HV = 'V' or 'v', then
the read direction is vertical or top-to-
bottom. If HV is any other character, the
read direction will be horizontal or left-
to-right.
See also GetStr
Example Read 'October' from 15,5 of Page 1.
GetHeap ( Page[1],h,15,5,7 );
-----------------------------------------------------------
GetSize Procedure
-----------------------------------------------------------
Purpose Returns the size of a disk file.
Declaration GetSize ( FileDesc:String; var Size:LongInt;
var Ecode:Integer );
Remarks Returns the number of bytes in the drive/path/
file specified by FileDesc. If Ecode = 0, the
file was found and Size = filesize. If Ecode
<> 0, then a problem occurred and Size is
unchanged.
Example Get the size of a file in bytes.
GetSize ( '\pascal\tp.exe',size,ecode );
if ecode = 0 then
write('Tp.Exe is ',size div 1024,'K');
-----------------------------------------------------------
GetStr Procedure
-----------------------------------------------------------
Purpose Reads a string from the screen.
Declaration GetStr ( hv:Char; S:String; X,Y:Integer;
Len:Byte );
Remarks Reads Len characters into S beginning at
(x,y) on the screen. If HV = 'V' or 'v' then
the read direction is vertical or top-to-
bottom. If HV is any other character, then
the read direction is horizontal or left-to-
right.
See also GetHeap
Example Read the date from the screen.
Assuming the string '12/25/89' begins
at 1,25 on the screen, then
GetStr ( h,Today,1,25,8 );
will store it in the string 'Today'.
-----------------------------------------------------------
Heap2Scr Procedure
-----------------------------------------------------------
Purpose Copies a block of heap to the screen.
Declaration Heap2Scr ( Hpage:HeapBuf; x1,y1,x2,y2,x3,y3:
Integer );
Remarks Copies the block on Page defined by (x1,y1)
and (x2,y2) to the screen beginning at
(x3,y3).
See also RestoreScreen,Scr2Heap
Example Display a menu on the current screen.
{--- Save the current screen ---}
SaveScreen ( Page[1] );
{--- Copy the menu to (60,1) of the
Screen ---}
Heap2Scr ( Page[2],1,1,15,10,60,1 );
{--- Wait for a keypress ---}
c := readkey;
if c = #0 then c := readkey;
.
.
{--- Erase the menu ---}
RestoreScreen ( Page[1] );
-----------------------------------------------------------
HeapAtt Procedure
-----------------------------------------------------------
Purpose Sets the video attributes of a screen image
stored on the heap.
Declaration HeapAtt ( Hpage:HeapBuf; x1,y1,x2,y2:Integer;
Att:Byte );
Remarks Sets all locations to attribute Att for the
block defined by (x1,y1) and (x2,y2) on Page.
See also SetAtt
Example Set the attributes of Page[1] to reverse video.
HeapAtt ( Page[1],1,1,80,25,112 );
-----------------------------------------------------------
Hex Function
-----------------------------------------------------------
Purpose Converts an integer to a hexadecimal string.
Declaration Hex ( DecimalValue : Word ) : String;
Result Type String
Remarks The four nibbles of DecimalValue are expressed
as a hexadecimal constant in ascii.
Example Express 16384 as a hex string.
write( Hex(16384) );
{ will display 4000 }
-----------------------------------------------------------
Hwipe Procedure
-----------------------------------------------------------
Purpose Horizontally wipes a block from the heap to
the screen.
Declaration Hwipe ( Hpage:HeapBuf; x1,y1,x2,y2,x3,y3,
delay : Integer );
Remarks Creates a horizontal wipe effect by writing
a block from the heap to the screen one
column at a time. Delay controls the speed
of the wipe.
Hwipe takes the block at (x1,y1) and (x2,y2)
and writes it to (x3,y3) of the screen.
See also Vwipe, Tile, SplitOpenH, SplitCloseH,
SplitOpenV, SplitCloseV
Example Wipe Page[1] to the screen.
Hwipe ( Page[1], 1,1,80,25,1,1,5 );
-----------------------------------------------------------
Input Procedure
-----------------------------------------------------------
Purpose Gets filtered data from the keyboard (Stdin).
Declaration Input ( x,y : Integer; Filter : String;
var Data : String; var LastCh : Char;
Att : Byte );
Remarks Positions the cursor at (x,y) and waits for
a keypress. The contents of Filter determine
which characters are accepted and placed in
Data. Input is terminated when an Esc, CR,
Tab, Reverse Tab, or EOF is received. The
terminating character is placed in LastCh.
Att is the attribute of the input characters
as they appear on the screen.
Input initializes Data to a string of blanks
equal in length to Filter. If the procedure
is terminated with an Esc, Data is returned
as a null string. Otherwise, Data is returned
with the accepted keypresses and the blanks.
Filter Values Allowable keystrokes or program
response
C Any character
D 0..9
I 0..9 space
R 0..9 . space
S + - space
space Input denied at this position;
cursor advanced right 1 position
All others Keystroke must match Filter
value.
Tab and Reverse Tab are used as terminators to
allow users to key data into multiple input
fields by tabbing between them.
Input accepts left and right cursor arrows
to move the cursor. When an end of field is
reached, Input wraps to the other end.
See also Input2
Example Accept the user's social security number.
{--- Define acceptable keystrokes ---}
Filter := 'DDD DD DDDD';
{--- Display the message and field format ---}
Message := 'Enter your SSN: ';
Len := Length(Message);
PutStr (h,Message,10,8,14 );
PutStr (h,'- -',Len+13,8,14);
{--- Get user's SSN ---}
Input ( Len+10,8,Filter,Data,LastKey,14 );
if LastKey <> #27 then begin
Data := strip(Data);
Data := translate(Data,'-',' ',' ');
end;
-----------------------------------------------------------
Input2 Procedure
-----------------------------------------------------------
Purpose Gets filtered data from the keyboard (Stdin).
Declaration Input2 ( x,y : Integer; Filter : String;
var Data : String; var LastCh : Char;
Att : Byte );
Remarks Positions the cursor at (x,y) and waits for
a keypress. Differs from Input Procedure by
allowing Function keys F1-F10 to terminate
processing.
-----------------------------------------------------------
LastPos Function
-----------------------------------------------------------
Purpose Returns the starting position of Needle in
HayStack by searching backwards.
Declaration LastPos ( Needle, HayStack : String;
Start : Integer ) : Integer;
Result Type Integer;
Remarks Begins at Start and proceeds towards the
beginning of HayStack until Needle is found
or HayStack is exhausted. If Needle is
found, LastPos returns its starting position
in HayStack. LastPos returns zero when:
- Needle is not found
- Needle is longer than HayStack
- Start is less than 1 or greater than
the length of HayStack
- Needle is null
- HayStack is null
See also PosR, Pos (Turbo Pascal)
Example Find the position of the last 's' in 'Boosters'.
LastS := LastPos ( 's','Boosters', 8);
{--- LastS will equal 8 ---}
-----------------------------------------------------------
Left Function
-----------------------------------------------------------
Purpose Left-justifies and pads a string in a field.
Declaration Left ( S : String; Width : Integer;
Pad : Char ) : String;
Result Type String
Remarks Returns S left-justified and padded on the
right with Pad characters, if necessary, in
a field of size Width.
See also Right, Center
Example Left-justify 'Name' for data entry.
Field1 := Left('Name ',35,'_');
-----------------------------------------------------------
Lower Function
-----------------------------------------------------------
Purpose Converts uppercase characters to lowercase.
Declaration Lower ( S : String ) : String;
Result Type String
Remarks Returns a string with all uppercase characters
of S converted to lowercase.
See also Upper
Example Ensure that a string is all lowercase.
S := Lower( S );